ctcheck

SafeNet Cryptoki provider status enquiry utility.

ctcheck lists the status of ProtectServer devices (actually, of SafeNet Cryptoki providers) in machine-readable format. This could be used, for example, in automatic monitoring of the devices' health and activity level.

The devices can be local hardware or remote, depending on which Cryptoki provider is used. Normally, the Cryptoki provider is specified by the file pointed to by the symbolic link:

/opt/safenet/protecttoolkit7/ptk/libcryptoki.so

If local hardware is used, the device driver package must be installed and running (check it with hsmstate command). If a remote Cryptoki is used, its IP address must be given with the CT_SERVER environment parameter.

The exact information printed is determined by the command line options. The globals are always printed, unless the -N option is present. By default, the most interesting parameters are printed (use the -h option to see the default outputs). The globals and per-device details are controlled separately by simple lists of desired parameters. For example, to print just the device serial numbers, the battery status and the initialization status, you would use a string like this with the -b option:

ctcheck -bserialnumber~batterystatus~deviceinitialised

Output format is either in XML format or as a ~ (tilde)-separated list. The XML format should be self-documenting.

The tilde output format (see Examples below) is as follows:

• Lines starting with # are comments and identify the fields in the following lines.

• The first non-comment line is the global information.

• Each subsequent non-comment line represents one device.

• Each line of information is a simple list of values each separated by the ~ (tilde) character (or as specified with the -s option)

Syntax

The following ctcheck syntax can can be used.

ctcheck [-a] [-b<string>] [-d<device>] [-f<x|s>] [-g<string>] [-h] [-n] [-N] [-s<char>] [-V]

-a, --all

Print all device information (overrides -b options)

-b<string>, --device-details=<string>

<string> specifies what device information to output in a ~ (tilde)-delimited list of parameters. Enclose the string in "quotation marks" or 'apostrophes' to avoid shell interpretation of the separator characters.

Parameters available:

• serialnumber - Serial number of device

• model - Device model

• devicerevision - Revision of device

• firmwarerevision - Revision of firmware on device

• ptkcrevision - Revision of ProtectToolkit-C on device

• deviceinitialised - 0 or 1. 0 may mean tampered.

• slotcount - Number of slots on a device.

• totalpublicmemory - Total secure memory - bytes or 'UNAVAILABLE'.

• freepublicmemory - Available secure memory - bytes or 'UNAVAILABLE'.

• freememory - Device's heap space (RAM) available - bytes or ‘UNAVAILABLE'.

• securitymode - 32-bit value or 'Default (No flags set)'

• transportmode - 32-bit value or 'None'

• batterystatus - LOW or GOOD

• eventlogfull - 0 or 1.

• fmsupport - 0 or 1

• batch - Device batch

• dateofmanufacture - YYYY:MM:DD hh:mm:ss

• clocklocal - YYYY:MM:DD hh:mm:ss

• pcbversion - Revision of PCB of device

• fpgaversion - Revision of FPGA of device

• externalpins - 32 bit value of external pin status

• eventlogcount - Number of entries in log

• fmlabel - Label of the FM inside the device

• fmversion - Version of the FM inside the device

• fmmanufacturer - Manufacturer of the FM inside the device

• fmbuildtime - Build time of the FM inside the device

• fmfingerprint - Fingerprint (hex string) identifying the FM image) of the FM

• fmromsize - Amount of ROM the FM is occupying or 'UNAVAILABLE'

• fmramsize - Amount of static RAM the FM is using or 'UNAVAILABLE'

• fmstatus - 'Enabled', 'Disabled', 'No FM' or 'ERROR'

-d<device>, --device=device

Just print details for device number device (the first device is number 0)

-f<x|s>, --format= x|s

Output format: x for XML, s for separator (Default)

-g<string>, --global-details=<string>

<string> specifies what global information to output in a ~ (tilde)-delimited list of parameters. Enclose the string in "quotation marks" or 'apostrophes' to avoid expansion by the shell. Parameters available:

• devicecount - Number of active devices.

• applicationcount - Number of applications currently using Cryptoki or 'UNAVAILABLE'

• totalsessioncount - Number of sessions open on all devices.

-h, --help

Display usage information.

-n, --number

Just print the number of devices

-N, --noglobals

Don't print the global information

-s<char>, --separator=<char>

Separator for output (default is ~)

-V, --version

Print the program version

Diagnostics

The program returns 1 if errors are encountered, else 0.

Examples

c:\>ctcheck
# global info: devicecount~applicationcount~totalsessioncount~
1~UNAVAILABLE~0~
# device info:  serialnumber~model~devicerevision~firmwarerevision~ptkcrevision~d
eviceinitialised~slotcount~totalpublicmemory~freepublicmemory~freememory~secu   rit
ymode~transportmode~batterystatus~eventlogfull~fmsupport~
518687~PSI-E2:PL220~6.00~5.00.06~5.3~TRUE~6~4091776~4054448~86986752~Default    (No
flags set)~None~GOOD~FALSE~TRUE~

c:\>ctcheck -fx
<?xml version="1.2" encoding="UTF-8"?>
<cryptoki>
        <devicecount>1</devicecount>
        <applicationcount>UNAVAILABLE</applicationcount>
        <totalsessioncount>0</totalsessioncount>
        <device>
                <serialnumber>518687</serialnumber>
                <model>PSI-E2:PL220</model>
                <devicerevision>6.00</devicerevision>
                <firmwarerevision>5.00.06</firmwarerevision>
                <ptkcrevision>5.3</ptkcrevision>
                <deviceinitialised>TRUE</deviceinitialised>
                <slotcount>6</slotcount>
                <totalpublicmemory>4091776</totalpublicmemory>
                <freepublicmemory>4054448</freepublicmemory>
                <freememory>86953984</freememory>
                <securitymode>Default (No flags set)</securitymode>
                <transportmode>None</transportmode>
                <batterystatus>GOOD</batterystatus>
                <eventlogfull>FALSE</eventlogfull>
                <fmsupport>TRUE</fmsupport>
        </device>
</cryptoki>

c:\>ctcheck -Nfx -b"serialnumber~batterystatus"
<?xml version="1.2" encoding="UTF-8"?>
<cryptoki>
        <device>
                <serialnumber>518687</serialnumber>
                <batterystatus>GOOD</batterystatus>
        </device>
</cryptoki>

See also

An awk(1) script called ctalarm(1m) is distributed with this program (not available for Windows) that post-processes the output of ctcheck(1m), decides if parameters are within site-specific limits and prints out an appropriate message. If parameters are not within limits, appropriate notices, warning or alarms can be raised. The script must be customized to the needs of the monitoring software being used and is provided as an example.